📖️️Traduction de https://gist.github.com/cedrickchee/55ecfbaac643bf0c24da6874bf4feb08(https://gist.github.com/cedrickchee/55ecfbaac643bf0c24da6874bf4feb08)
Un résumé des principales idées du livre "Clean Code : A Handbook of Agile Software Craftsmanship" de Robert C. Martin (alias Oncle Bob).
Le code est propre s'il peut être compris facilement - par tous les membres de l'équipe. Un code propre peut être lu et amélioré par un développeur autre que son auteur original. Avec la compréhensibilité viennent la lisibilité, la modifiabilité, l'extensibilité et la maintenabilité.
1. Règles générales
1.1 Suivez les conventions
* Restez simple et stupide. Le plus simple est toujours le mieux. Réduisez la complexité autant que possible.
* Règle des scouts. Laissez le terrain de camping plus propre que vous ne l'avez trouvé.
* Toujours trouver la cause profonde. Cherchez toujours la cause profonde d'un problème.
* Suivez le principe de la moindre surprise.
* Ne vous répétez pas (DRY).
* Ne pas passer outre les sécurités.
2. Règles de conception
* Gardez les données configurables (ex. : constantes) à un niveau élevé. Elles doivent être faciles à modifier.
* Préférez le polymorphisme à if/else ou switch/case.
* Séparer le code multithreading.
* Empêcher la sur-configurabilité.
* Utiliser l'injection de dépendances.
* Suivre la loi de Déméter. Une classe ne doit connaître que ses dépendances directes.
3. Conseils de compréhensibilité
* Soyez cohérent (consistent). Si vous faites quelque chose d'une certaine manière, faites toutes les choses similaires de la même manière.
* Utilisez des noms de variables explicites.
* Encapsulez les conditions limites. Il est difficile de garder une trace des conditions limites. Mettez le traitement de ces conditions à un seul endroit.
* Préférez les objets aux types primitifs.
* Évitez les dépendances logiques. N'écrivez pas de méthodes qui fonctionnent correctement en fonction de quelque chose d'autre dans la même classe.
* Évitez les conditions négatives.
4. Règles relatives aux noms
* Choisissez des noms descriptifs et non ambigus.
* Faites des distinctions significatives.
* Utilisez des noms prononçables.
* Utilisez des noms faciles à chercher (évitez les noms très courts, très récurrents).
* Remplacer les nombres magiques par des constantes nommées.
* Évitez les codages. Ne pas ajouter de préfixes ou d'informations de type.
5. Règles de fonctions
* Petites.
* Elles ne font qu'une chose et doivent la faire bien.
* Utilisez des noms descriptifs.
* Préférez moins d'arguments. Pas plus de 2 arguments si possible.
* N'ont pas d'effets de bord (ie. se limite à ce qu'elles sont censées faire).
* Ne pas utiliser d'arguments de type "
flag(https://martinfowler.com/bliki/FlagArgument.html)". Diviser la méthode en plusieurs méthodes indépendantes qui peuvent être appelées depuis le client sans ce type d'argument.
6. Règles de commentaires
Essayez toujours de vous expliquer dans le code. Si ce n'est pas possible, prenez votre temps pour écrire un bon commentaire.
* Ne soyez pas redondant (par exemple : i++ ; // incrémente i).
* N'ajoutez pas de commentaires évidents. (par exemple: ->save() // sauvegarde la donnée).
* N'utilisez pas d'accolades fermantes (par exemple : } // fin de fonction).
* Ne commentez pas le code mort. Supprimez-le plutôt.
* Utiliser les commentaires pour expliquer l'intention.
* Utiliser les commentaires pour clarifier le code.
* Utiliser les commentaires pour avertir des conséquences.
7. Structure du code source
* "Séparez les concepts verticalement."
* "Le code connexe doit apparaître verticalement dense."
* Déclarez les variables à proximité de leur utilisation.
* Les fonctions dépendantes doivent être proches.
* Les fonctions similaires doivent être proches.
* Placez les fonctions dans le sens de la descente.
* Gardez les lignes courtes.
* N'utilisez pas l'alignement horizontal.
* Utilisez les espaces blancs pour associer des éléments connexes et dissocier des éléments faiblement connexes.
* Ne rompez pas l'indentation.
8. Objets et structures de données
* Cachez la structure interne.
* Préférez les structures de données.
* Évitez les structures hybrides (moitié objet et moitié données).
* Doivent être petites.
* Ne font qu'une seule chose.
* Un petit nombre de variables d'instance. Si votre classe a trop de variables d'instance, alors elle fait probablement plus d'une chose.
* La classe de base ne doit rien savoir de ses dérivés.
* Mieux vaut avoir plusieurs fonctions que de passer du code dans une fonction pour sélectionner un comportement.
* Préférez les méthodes non statiques aux méthodes statiques.
9. Tests
* Une assertion par test.
* Rapide.
* Indépendant.
* Répétable.
* Auto-validation.
* Rapide.
* Lisible.
* Facile à exécuter.
* Utilisez un outil de couverture.
10. Senteurs du code
* Rigidité. Le logiciel est difficile à modifier. Une petite modification entraîne une cascade de modifications ultérieures.
* Fragilité. Le logiciel se casse en de nombreux endroits à cause d'une seule modification.
* Immobilité. Vous ne pouvez pas réutiliser des parties du code dans d'autres projets en raison des risques encourus et de l'effort élevé.
* Complexité inutile.
* Répétition inutile.
* Opacité. Le code est difficile à comprendre.
11. Gestion des erreurs
Ne mélangez pas la gestion des erreurs et le code.
Utilisez des exceptions au lieu de renvoyer des codes d'erreur.
Ne retournez pas null, ne passez pas null non plus.
Lancez les exceptions avec le contexte.